IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/relnotes/WorkShop/ch5.z/ch5

Text File | 1998-11-02 | 118.5 KB | 2,905 lines

                                  - 1 -



       5.  _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__W_o_r_k_a_r_o_u_n_d_s

       5.1  _W_o_r_k_S_h_o_p__D_e_b_u_g_g_e_r

          +o The 2.6.5 version of the WorkShop debugger has problems
            evaluating references to class data members and the
            "this" pointer in C++ programs compiled with the 7.1
            and 7.0 versions of the C++ compiler.

            Workaround: You can recompile your code using the 7.2
            version of the compiler.  These expressions work
            correctly with the output of the 7.2 compiler.  If you
            must debug 7.1 or 7.0 generated programs or DSOs, add
            the following line to your .Xdefaults file:

            ****uuuusssseeeeOOOOllllddddEEEExxxxpppprrrrEEEEvvvvaaaallll:::: ttttrrrruuuueeee
            ****UUUUsssseeeeOOOOllllddddEEEExxxxpppprrrrEEEEvvvvaaaallll:::: ttttrrrruuuueeee

            This will allow you to reference class data members,
            but you will have to reference them as "this->member".


          +o There is a limitation in the specification of the type
            for a C++ exception trap.  The determination as to
            whether a particular type has been thrown does not take
            into account typedefs.  For example, given the type
            definition:

            ttttyyyyppppeeeeddddeeeeffff cccchhhhaaaarrrr ****SSSSttttrrrriiiinnnngggg;;;;

            setting the breakpoint:

            ssssttttoooopppp eeeexxxxcccceeeeppppttttiiiioooonnnn SSSSttttrrrriiiinnnngggg

            would have no effect.

            Workaround:  Use the base type specified in the typedef
            when setting the breakpoint.

          +o After using cvd's Trap menu to change the setting of
            Group Trap Default or Stop All Default, after an
            extended period a dialog box may display the message
            "Error: No debugger available to set trap modes".  This
            can be ignored.

          +o When parameter declaration inside a subroutine uses (*)
            type of syntax i.e.  character *(*), cvd will not be
            able to display its content correctly. (Incident
            #178191)













                                  - 2 -



          +o Memory leak experiments might fail to unwind the stack
            when particular functions are found in the stack (such
            as usinit() from IRIX 6.2 libc or some libgl
            functions).

            Workaround:  There is no good workaround for this
            problem.

          +o The ability to unwind the call stack using the Call
            Stack View does not work reliably. Stack traces will be
            incomplete when stopped in a signal handler of a 4.X
            binary running on a 5.X or a 6.X system. Returning from
            the signal handler using "step into", "step over" and
            "return" will not work correctly.  Similarly,
            registering a signal through sigaction call with the
            SA_SIGINFO flag set may cause incorrect stack traces
            when stopped in the signal handler. (Incident #215151)

            Workaround:  There is no good workaround for this
            problem.

          +o On 5.X, 6.0, and 6.1 systems the debugger has trouble
            detecting mismatches between an executable and core
            file (the problem is resolved on 6.2 systems).  If this
            problem occurs, you are likely to receive an incorrect
            stack trace without any warning that the core file may
            not be based on the given executable. (Incident
            #186347)

          +o The views that do expression evaluation, Expression
            View, the Evaluate Expression dialog box, Structure
            Browser, Variable Browser, Array Visualizer, and the
            Debugger command line cannot yet evaluate:

               - long double (C/C++) and unsigned variants

               - real * 16 (Fortran) and unsigned variants

               - complex *32 (Fortran) and unsigned variants

            Evaluation of these types is not available at this
            time.  (Incident #206313)

          +o Making an interactive function call when the target
            process is sleeping in a system call will cause the
            target to fault. (Incident #223601)

          +o WorkShop does not accommodate text editors other than
            Source View very well.













                                  - 3 -



            Workaround:  Set the _e_d_i_t_o_r_C_o_m_m_a_n_d resource in the
            _a_p_p-_d_e_f_a_u_l_t_s file to your desired editor.  For example,
            set _e_d_i_t_o_r_C_o_m_m_a_n_d to _w_s_h -_c _v_i +%_d to run _v_i in a _w_s_h
            window. You also need to set *_u_s_e_T_o_o_l_T_a_l_k to _F_a_l_s_e.

          +o The request to kill a process which has spawned child
            processes (through _f_o_r_k(), _s_p_r_o_c(), or _s_p_r_o_c_s_p()),
            followed by exiting _c_v_d, may not properly terminate the
            descendant processes. The descendant processes may
            continue to run after _c_v_d has exited.  (Incident
            #206273)

            Workaround:  Kill all of the process group members with
            the Multiprocess View as opposed to using the Main
            View.  If any of the descendant processes were created
            through a _f_o_r_k(), you will have had to direct the
            Multiprocess View to attach to _f_o_r_k()ed process (see
            ``Config: Preferences'' in the Multiprocess View).

          +o The Multiprocess View is known to occasionally not
            display all process group members which _c_v_d is attached
            to.  One condition where this problem occurs is when
            the list of processes shown by the Multiprocess View is
            frequently changing in a short span of time (for
            example, processes are _f_o_r_k()ed which _e_x_e_c() and exit
            shortly after they start).  (Incident #244782)

            Workaround:  Use of Stop in the Multiprocess View will
            cause _c_v_d to stop all process group members and the
            display should change to correctly list all processes.

          +o When _c_v_d is brought up on one member of a running
            shared process group (see _s_p_r_o_c(2)), _c_v_d does not
            identify and attach to all of the other processes which
            are members of the shared process group. If you start
            up the Multiprocess View you will only see the process
            you started _c_v_d on.  The correct behavior from the
            Multiprocess View would be to display all members of
            the shared process group.  (Incident #179940)

            Workaround:  Use ``Process: Add'' in the Multiprocess
            View to manually add each member of the shared process
            group to the _c_v_d process group display by Multiprocess
            View.

          +o Attempts to add a process which has been removed from
            Multiprocess View may fail or lead to an abort of the
            Multiprocess View.  (Incident #168934)

          +o Disassembly View sometimes has problems when two or
            more DSOs have overlapping text.  In such cases,











                                  - 4 -



            Disassembly View displays only one of the DSOs from the
            set whose text overlaps. This can happen to users who
            are building their own DSOs.  Unfortunately _c_v_d does
            not warn the user when this type of conflict occurs.
            (Incident #204024)

          +o On attempting to locate the DSOs used by an executable,
            _c_v_d uses the shell environment in which _c_v_d was
            started, as opposed to the shell environment within the
            Execution View.  This means that the value of
            environment variables like LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which are
            used by _c_v_d may not match the values in the shell where
            the executable will be run.  When _c_v_d is using the
            wrong values for environment variables like
            LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH, it may have trouble finding all of the
            appropriate DSO symbol tables.  When _c_v_d has trouble
            finding DSOs used by an executable it will display the
            Library Search Path dialog to call attention to the
            DSOs which could not be found. (Incidents #224125,
            #236651)

            Workaround:  Use ``Admin: Library Search Path ...'' to
            examine and set environment variables like
            LLLLDDDD____LLLLIIIIBBBBRRRRAAAARRRRYYYY____PPPPAAAATTTTHHHH which control the identification of
            DSOs.

          +o Watchpoints in _c_v_d may be defined with an address and
            size or an expression.  If you attempt to watch an
            expression which resides on the stack (for example, a
            local variable) _c_v_d will not allow definition of the
            trap.  _c_v_d will only watch expressions whose location
            is within a mapping other than the stack.  (Incident
            #197233)

            Workaround:  If you want to watch an expression which
            resides on the stack, use the expression evaluator to
            find the address of the expression and create the
            watchpoint using the address.  Once the expression is
            deallocated, the watchpoint should be removed to avoid
            any confusion when the stack address is reused for some
            other purpose later on in the execution.

          +o Process group watchpoints involving expressions are not
            supported well.  If you create a watchpoint with a
            command like ppppggggrrrrpppp wwwwaaaattttcccchhhh <<<<eeeexxxxpppprrrreeeessssssssiiiioooonnnn>>>>, the expression is
            only evaluated once on one of the process group
            members.  The evaluation is used to determine the
            address and size of the watchpoint, and address and
            size is used to create a watchpoint on each process
            group member.  This will only work correctly if the
            address and size of the expression is the same for each











                                  - 5 -



            process group member.  There is no workaround known for
            this problem.  (Incident #143367)

          +o The Trap Manager fails to properly define watchpoints
            on 64-bit addresses.  The address typed in the
            ``Trap:'' field is corrupted and either a watchpoint is
            created on the wrong address or an invalid address
            error is reported (_W_a_t_c_h_p_o_i_n_t _a_d_d_r_e_s_s _r_a_n_g_e _i_n_c_l_u_d_e_s _a_n
            _i_n_v_a_l_i_d _v_i_r_t_u_a_l _a_d_d_r_e_s_s.).  (Incident #235635)

            Workaround: The command line interface panel in the _c_v_d
            Main View can be used in place of the Trap Manager to
            enter the watchpoint command.

          +o _c_v_d does not have support for weak symbols (see
            Appendix A of the _C _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l).  _c_v_d
            will not recognize the weak symbol name.  For example,
            _c_v_d will not accept a request to trap on entry to
            dlopen.  (Incident #181409)

            Workaround:  Use the "strong" symbol name in place of
            the weak one.  Many weak symbols defined in libc have
            corresponding "strong" symbol names which are the weak
            name with a ``_'' prepended onto the front.  For
            example, the "strong" symbol name for dlopen is
            _dlopen.

          +o A write watchpoint may fail to fire when the write
            occurs within a syscall.  For example, a write
            watchpoint on one word within a buffer written by read
            may fail to fire.

            Workaround:  Define the watchpoint to cover the entire
            data structure as opposed to a subset of the structure.
            For example, define the watchpoint over the entire
            buffer being handed to read as opposed to a single
            word.

          +o An attempt to step into the first call to an external
            function will behave like a step over.  The first call
            to an external function invokes rld to resolve the
            function address.  When this occurs the request to step
            into the call will look like a step over to the user.
            (Incident #147302)

            Workaround: Either set the environment variable
            _L_D__B_I_N_D__N_O_W to 1 in the Execution View prior to running
            the program (see _r_l_d(1)) or use function entry
            breakpoints.













                                  - 6 -



          +o Traps placed within a parallel Fortran DO loop, created
            with the C$DOACROSS compiler directive, fail to work
            correctly.  Although the traps appear to be placed
            correctly on 6.0 systems, the process will not stop on
            the traps.  On 5.3 systems the traps cannot be placed
            within the loop at all.  (Incident #20818)

            Workaround:  On a 6.0 system _d_b_x can be used
            successfully to place traps within the loop.

          +o The Fortran intrinsics _c_h_a_r, _z_e_x_t, _s_e_c_o_n_d_s, _m_a_l_l_o_c, and
            _e_p are not supported.  (Incident #206293)

          +o The debugger does not understand external or intrinsic
            statements in the Fortran program.  If the program has
            a function by the same name as an intrinsic function,
            evaluating an expression involving that function will
            always cause the program function to be called.

          +o Some of the intrinsics (_s_q_r_t, _e_x_p, _l_o_g, _l_o_g_1_0, _s_i_n,
            _c_o_s, _t_a_n, _a_s_i_n, _a_c_o_s, _a_t_a_n, _s_i_n_h, _c_o_s_h, _t_a_n_h) do not
            give the correct results when the debugged executable
            is linked with _l_i_b_m._s_o.  This is because of entry
            points with similar names in _l_i_b_m._s_o.

            Workaround: Use a specific intrinsic name.  For
            example, _s_i_n(_r_1) where _r_1 is real will produce
            incorrect results.  On the otherhand, _d_s_i_n(_d_f_l_o_a_t(_r_1))
            will give correct results, with the results being a
            _r_e_a_l *_8 quantity.

          +o Stopping in the entry prologue of a function (before
            the first user statement) in a Fortran program and
            evaluating an expression that involves an adjustable
            array or displaying an adjustable array in the Array
            Visualizer will not work correctly.  (Incident #206264)

            Workaround: Step to the first user statement and
            evaluate the expression.

          +o When stopped in a Fortran function/subprogram that has
            alternate entry points, the debugger will not list all
            the arguments of the subprogram and their values
            correctly.  (Incident #164327)

          +o For global lookups, _c_v_d acts as though all DSOs are
            built ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  If a process is stopped within a
            DSO and the user asks _c_v_d to lookup a global variable
            or function, _c_v_d will always look within the DSO before
            it considers the main program or any other DSO.  In
            effect, _c_v_d is acting as if each DSO has been built











                                  - 7 -



            with ----BBBB ssssyyyymmmmbbbboooolllliiiicccc.  (Incidents #173343)

          +o Interactive calls to inline member functions of C++
            classes is not supported.

          +o There is no support for C++ overloaded operators in the
            expression evaluator.  (Incident #203968)

          +o The debugger does not have full support for C++
            templates.  However, the user can stop in template code
            and print the ``this'' pointer.  (Incidents #140313,
            #140316, #222352)

          +o The display format for describing an array pointer
            types is incorrect.  For example, an array of
            double(*)[2] is expressed as double[]*.

          +o Elements of Fortran arrays with more than 6 dimensions
            (or 5 dimensions, if the element type is character
            string) cannot be referenced.

          +o C++ objects containing virtual base classes do not
            display correctly in the expression evaluator.
            (Incident #190170)

          +o _c_v_p_c_s can stack trace through assembler alternate entry
            functions only when they are at the same address as the
            main entry point.  Assembler functions with arbitrary
            alternate entry points will produce incorrect stack
            trace.

          +o When the Trap Manager is invoked, traps are
            automatically loaded from the ._c_v_T_r_a_p_M_g_r file if one
            exists.  However, these traps are reloaded if the Trap
            Manager is closed and restarted.  (Incident #79217)

            Workaround: The Trap Manager should either be left
            running or the default traps should be stored in a
            different file and reloaded manually when desired.

          +o In general, when a write watchpoint fires, the write is
            simulated by the debugger to show the new value before
            any trap conditional is evaluated.  The four exceptions
            for this case are the SC, SCD, SDL, and SDR
            instructions.  (Incident #250036)

          +o A kernel bug prevents watchpoints from firing reliably
            for members of share process groups (such as Power
            Fortran or Power C programs).  Watchpoints work
            reliably for non-shared text and data segments in each
            individual process.











                                  - 8 -



          +o If you stop a process through job control, the debugger
            may not display an accurate status of the process, and
            process control requests do not take effect until the
            process is resumed through job control.  A process is
            stopped through job control with <Ctrl-Z> from the
            shell or when it receives one of the signals: SIGSTOP,
            SIGTSTP, SIGTTIN, and SIGTTOU.  A process is resumed
            through job control with _f_g and _b_g from the shell or
            when it receives the signal SIGCONT.  If a running
            process is stopped through job control, the debugger
            continues to show that the process is running.  When
            attaching to a process stopped through job control, the
            debugger shows that the process is stopped.  (Incident
            #167693)

          +o For instrumented executables (used for performance
            analysis), stack frame unwinding may be incomplete when
            stopped in a signal handler; the unwinding may stop
            prematurely after the ``_sigtramp'' frame.  (Incident
            #71307)

            Workaround: A full stack trace may be maintained by
            returning past the ``_sigtramp'' frame.

          +o The demo program _j_e_l_l_o cannot be built as described in
            the tutorial without the library /_u_s_r/_l_i_b/_l_i_b_g_l._s_o.

            Workaround:  This library should be installed when IRIX
            is installed (eoe1.sw.gfx_lib subsystem).

          +o Processes that use the blocking capabilities as
            provided by _b_l_o_c_k_p_r_o_c(2) may not terminate as expected
            upon completion of a debug session.  Such processes are
            left in a blocked state with a SIGKILL pending.

            Workaround:  These processes can be terminated with
            _k_i_l_l(1).

          +o The modification of an inactive trap will cause the
            trap to become active.  You will have to toggle the
            active button next to the trap description in order to
            deactivate the trap.  (Incident #190278)

          +o There is a case where the path remapping component of
            WorkShop will find the wrong file.  When _c_v_d is stopped
            and started multiple times, and ``Admin:Exit'' was used
            to exit _c_v_d, the path remapping component will retain
            entries in its Substitution Set from each debugging
            session (see ``Admin:Project:Remap Paths...'').  The
            path remapping component of _c_v_d is implemented as a
            separate process and the ``.'' entry in the











                                  - 9 -



            Substitution Set refers to the directory in which the
            process was started, typically the directory were the
            first _c_v_d was started.

            Workaround: Use ``Admin:Project:Exit'' in place of
            ``Admin:Exit''.  This will force the path remapping
            process to terminate on each exit of _c_v_d.

          +o By default the debugger will not attach to a _f_o_r_k()ed
            process unless the fork occurs during an interactive
            function call.  If you have used the Multiprocess View
            preferences dialog to prevent a forked child from being
            resumed, and you make an interactive function call will
            leads to a call on fork, the child process will be left
            stopped on exit from fork.  You must now use the
            Multiprocess View to resume the child process.
            (Incident #190308)

          +o _c_v_d may fail to recognize that a DSO source file is
            newer than the DSO.  Although such a source file may be
            the wrong version for the code which is executing, _c_v_d
            will not issue a warning. The source of the problem is
            that _c_v_d is always comparing time of last modification
            for the source file against the executable when it
            should be comparing against the DSO.  (Incident
            #181297)

          +o Fortran COMMON block members that are at an offset
            greater than 8 Megabytes from the start of the common
            block will not be evaluated correctly in an expression.

          +o When using the Switch Process dialog to attach to an
            existing process, don't attach to one of the CaseVision
            or WorkShop processes (e.g. _c_v_p_a_t_h_R_e_m_a_p, _c_v_m_a_i_n) or the
            environment may hang. Should this happen, kill the
            _c_v_m_a_i_n process and start over.

          +o Occasionally, _c_v_m_a_i_n will dump core at startup if you
            have an executable with a mismatched core file and your
            NetLS license is within 90 days of expiring.  If this
            happens, restart _c_v_d.

          +o The request to print the content of a very large data
            structure (such as an array) from within the main
            window's command line interface panel may lead to an
            abort of _c_v_d.  (Incident #227980)

            Workaround:  The Array Browser may be used to display
            very large arrays.













                                  - 10 -



          +o The main window's command line interface panel will
            only display the first 100 elements of an array.  There
            is no way to change this behavior.  (Incident #250028)

            Workaround:  The best way to examine an array is the
            Array Browser.

          +o With an executable built with the DCC compiler,
            attempts at retrieving symbolic information about
            _o_s_t_r_e_a_m may lead to an abort of _c_v_p_c_s.  Entering the
            command wwwwhhhhaaaattttiiiissss oooossssttttrrrreeeeaaaammmm in _c_v_d will lead to such an
            abort.  (Incident #239838)

          +o The _c_v_p_c_s component of _c_v_d is known to abort on very
            large COFF format executables. (Incident #244495)

          +o The command line interface panel in the _c_v_d Main View
            may fail to evaluate expressions when the process is
            stopped and the language of the current context is
            Assembler. (Incident #246294)

            Workaround: The Expression View can be used in place of
            the command line interface panel.

          +o After a process has stopped, an expression value may
            become invalid due to evaluation of another expression
            or use of debugger commands which can lead to
            modification of expression values.  An example would be
            the value of a variable displayed in Expression View
            which is not recalculated after the variable is updated
            with the _a_s_s_i_g_n command in the command line interface
            panel.  (Incident #247050)

            Workaround: Force the value of the expression to be
            recalculated by retyping the expression.

          +o The Array Visualizer will no longer implicitly use _t_h_i_s
            on a C++ program.  When attempting to display the
            member of a class you will have to explicitly include
            _t_h_i_s-> along with the name of the member.  (Incident
            #248882)

          +o Use of the division, and modulus operators in the
            ``Indexing Expression:'' field of the Array Visualizer
            may not work correctly on 64-bit executables.
            (Incident #249262)

          +o On startup _c_v_d connects to an underlying process
            control server.  Due to a change in WorkShop 2.4, when
            _c_v_d is using a version of the communication protocol
            which is incompatible with the version used by the











                                  - 11 -



            server it can no longer recognize the condition and
            report the incompatible version numbers.  As in
            previous versions of WorkShop, _c_v_d will exit, but it
            will no longer report the mismatch of communication
            protocol versions. (Incident #233399)

          +o _c_v_d may not list all the member functions of a class
            correctly when the class and its member functions are
            built into a separate DSO.  (Incident #249733)

          +o If the application uses the isolate process (or CPU
            pinning) feature of IRIX, the thread pinned to a
            specific CPU cannot be debugged.  The isolate process
            feature is accessed by a call to _s_y_s_m_p(_M_P__I_S_O_L_A_T_E).
            (Incident #216158)

            Workaround: Disable calls to _s_y_s_m_p(_M_P__I_S_O_L_A_T_E) to
            enable debugging.

          +o Occasionally, path remapping will cease to function
            properly: new entries in the list will not take
            immediate effect, yet if you exit and restart _c_v_d, they
            will apply. (Incident #247133)

            Workaround: Exit _c_v_d and kkkkiiiillllllllaaaallllllll ttttttttsssseeeessssssssiiiioooonnnn.

          +o _c_v_d cannot evaluate expressions involving local classes
            (classes that are defined inside of a function).
            (Incident #212268)

          +o The Query menu within _c_v_d will fail to operate
            correctly if _c_v_d was attached to a running process (ccccvvvvdddd
            ----ppppiiiidddd ............)  or if _c_v_s_t_a_t_i_c is started by hand (``Admin:
            Launch Tool -> Static Analyzer'').   (Incident #238595)

          +o A trap at the closing brace of a C/C++ function may not
            be defined properly.  This is known to occur when the
            last statement of the function is a return statement.
            When this problem occurs the trap is defined on a
            source line following the closing brace, typically the
            opening brace of the next function.

            Workaround: Place the trap on the source line
            containing the return statement as opposed to the line
            containing the closing brace.   (Incident #277136)

          +o _c_v_d may close file descriptors it should leave open in
            the _r_u_n command.  All file descriptors at 3 and above
            are closed by _c_v_d.   (Incident #277295)













                                  - 12 -



          +o The Structure Browser is known to abort when asked to
            display more than 100 elements of a linked list.
            (Incident #278140)

          +o The _c_v_p_c_s component of _c_v_d is known to occasionally
            abort on erroneous expression evaluation requests from
            the one-time expression evaluation component of _c_v_d.
            (Incident #282160)

          +o Evaluation of a C++ expression which contains a
            variable whose name is the same as that of a structure
            may lead to an erroneous error.   (Incident #286949)

          +o When stopped at the entry to a function compiled N32 or
            64-bit the debugger's Call Stack View does not always
            report the correct arguments to that function.  Usually
            the arguments will be correct after stepping one or
            more lines into the function.

          +o Under some conditions, on some R5K Indy and O2
            machines, a hardware problem may cause traps to not
            fire the first time they are encountered.  Rerun often
            works around the problem (Incident #439770).

       5.1.1  _D_e_b_u_g_g_i_n_g__6_4_-_b_i_t__a_n_d__N_3_2__C_+_+__p_r_o_g_r_a_m_s  This section
       discusses problems that are unique to debugging 64-bit and
       N32 C++ programs.  (The problems discussed in the previous
       section may also apply to 64-bit and N32 C++ debugging.)

       The first two problems on the following list are limitations
       of this release of the debugger; they will be fixed in a
       future release.  The remaining problems will be fixed by a
       future release of the C++ compiler.

          +o Interactive function calls to member functions cannot
            be performed through objects of the class using the ->
            or . access operators.

            Workaround: Perform the interactive function call using
            the class-qualified name.  In such a call, the _t_h_i_s
            parameter must be passed explicitly.

            ccccllllaaaassssssss nnnnooooddddeeee {{{{
                nnnnooooddddeeee ****____rrrriiiigggghhhhtttt;;;;
                nnnnooooddddeeee ****____lllleeeefffftttt;;;;
            ppppuuuubbbblllliiiicccc::::
                nnnnooooddddeeee(((())));;;;
                nnnnooooddddeeee**** rrrriiiigggghhhhtttt(((())));;;;
                nnnnooooddddeeee**** lllleeeefffftttt(((())));;;;
            }}}};;;;
            nnnnooooddddeeee ****nnnn;;;;











                                  - 13 -



            In this example, the member functions cannot be called
            as _n->_r_i_g_h_t() or _n->_l_e_f_t().  Instead, they must be
            called as _n_o_d_e::_r_i_g_h_t(_n) or _n_o_d_e::_l_e_f_t(_n).

          +o The _t_h_i_s parameter is not explicitly dereferenced in
            member functions.

            Workaround: Access members of the _t_h_i_s parameter in a
            member function by using the _t_h_i_s-> accessor.

          +o There is no debugging output for anonymous unions
            declared in a block. (Incident 236926)

          +o Static data members cannot be accessed using the -> or
            . access operators. (Incident 237006)

            Workaround: Access static data members using the
            class-qualified name.

          +o Static member functions cannot be accessed using the ->
            or . access operators, or by using the class-qualified
            name. (Incident 237029)

            Workaround: Access static member functions using only
            the name of the member function; do not use the class-
            qualified name.

          +o Nested C++ classes appear as global classes.  (Incident
            242800)

          +o The tag for nested C++ structures is incorrect.
            Instead of the correct tag name, the C++ mangled name
            is used. (Incident 244522)

          +o The type is incorrect for point-to-member variables.
            Instead of having the correct pointer-to-member type,
            these variables have the type of the member to which
            they're pointing. (Incident 249844)

          +o The definition of a template class instantiation does
            not include the member functions. (Incident 249849)

            Workaround: A member function definition for a template
            class instantiation may be printed out using the
            class-qualified name, prefixed by the template argument
            list. For example, consider the following code segment:

            tttteeeemmmmppppllllaaaatttteeee<<<<ccccllllaaaassssssss TTTT>>>> ccccllllaaaassssssss vvvveeeeccccttttoooorrrr {{{{
                TTTT**** vvvv;;;;
                iiiinnnntttt sssszzzz;;;;
            ppppuuuubbbblllliiiicccc::::











                                  - 14 -



                vvvveeeeccccttttoooorrrr((((iiiinnnntttt))));;;;
                TTTT&&&& ooooppppeeeerrrraaaattttoooorrrr[[[[]]]]((((iiiinnnntttt))));;;;
            }}}};;;;
            vvvveeeeccccttttoooorrrr<<<<iiiinnnntttt>>>> vvvv1111((((22220000))));;;;

            In this example, the global names of the member
            functions are <_i_n_t>_v_e_c_t_o_r::_v_e_c_t_o_r and
            <_i_n_t>_v_e_c_t_o_r::_o_p_e_r_a_t_o_r[].

       5.1.2  _D_e_b_u_g_g_i_n_g__P_r_o_g_r_a_m__G_r_o_u_p_s__I_n_c_l_u_d_i_n_g__a__S_e_t_-_u_i_d__P_r_o_g_r_a_m
       Because of standard IRIX security policies, the debugger can
       not debug a program running as another user (unless you are
       logged in as _r_o_o_t).  This restriction applies even to system
       programs which are set-UID, and even when all you want to do
       with the set-UID program is debug something that it in turn
       runs.  It is common to use the system-provided set-UID
       program _x_w_s_h (or _w_i_n_t_e_r_m, which in turn runs _x_w_s_h) in this
       way.

       There are two basic ways to deal with this problem.  You can
       become _r_o_o_t before starting your debugging session, which
       grants you all necessary access rights (but may be
       infeasible for your application or situation).  Or, you can
       arrange to use a non-set-UID copy of the intermediary
       program, for example with _c_h_m_o_d, or by making a copy of the
       program with _c_p.

       There is also a bug in the IRIX 6.0 version of _x_w_s_h which
       makes it unreliable if run non-set-UID.  You may be able to
       use _x_t_e_r_m instead of _x_w_s_h for these applications, for
       example by using _w_i_n_t_e_r_m and setting the environment
       variable WWWWIIIINNNNTTTTEEEERRRRMMMM to xxxxtttteeeerrrrmmmm before starting your debugging
       session (and providing a non-set-UID copy of _x_t_e_r_m).

       If your application depends on features of _x_w_s_h, can not use
       _x_t_e_r_m instead, and can not be run as _r_o_o_t, then this
       procedure will generally ensure that you can debug as non-
       root:

          +o Make a non-set-uid copy of _x_w_s_h (ccccpppp ////uuuussssrrrr////ssssbbbbiiiinnnn////xxxxwwwwsssshhhh ....).

          +o Start several _x_w_s_h or _x_t_e_r_m windows, as the user who
            will be doing the debugging.  Exit them all.  It is
            important that they all be started together, all be
            running at once, and then be exited immediately before
            the debugging session begins.

          +o Debug your application.

          +o Set one or more breakpoints by function name ("stop in
            main"), in the syscall panel, or with the ``Traps: Stop











                                  - 15 -



            at Function Entry'' menu - not by clicking in the glyph
            bar of the main window.  (Traps set on a particular
            source line, as by clicking, are not copied from one
            program to the next.)

          +o Bring up the MPView, from the Admin menu.

          +o Be sure all the "copy traps...." boxes are checked in
            its configuration dialog.

          +o Run your application, using MPView's ``Continue''
            button as necessary and watching MPView for the
            appearance of your subprocess.  Double-click it to
            launch a debugger on it.


       5.2  _W_o_r_k_S_h_o_p__F_i_x_+_C_o_n_t_i_n_u_e

       5.2.1  _L_i_m_i_t_a_t_i_o_n_s__o_f__F_i_x_+_C_o_n_t_i_n_u_e

          +o You cannot add or delete global variables or functions.

          +o You are restricted to editing the bodies of existing
            non-inline functions. If you attempt to edit an inline
            function, no warnings are emitted, but the results are
            unpredictable.

            Incident 240481

          +o You cannot modify a function while the program is
            sleeping in a system call, or is stopped on entry to a
            system call.  The debugger will detect this condition
            and prevent you from loading the modified function
            until you return from the system call.

            You can set a trap on exit from the system call using
            the System Call panel of cvd and continue the program
            in order to get to a point where function loading is
            allowed.

            Incident 244664

          +o The Multiprocess View capability of the debugger does
            not interact well with the Fix and Continue feature.
            sproc'ed and forked processes inherit the new
            redefinition of the function.  However, when starting a
            debugger session on the new process, the debugger is
            not aware that the process contains function
            redefinitions.  This means that there is no way to
            deactivate the new definition in the new process after
            a sproc() or a fork(). If the new function definition











                                  - 16 -



            is not desired in the new process, it is necessary to
            stop the process on entry to fork() or sproc(),
            deactivate the modified function and activate it again
            on exit from fork() or sproc().

          +o Performance Analysis and Fix and Continue are mutually
            exclusive operations.  You should not run a performance
            experiment after you have modified a function.  In most
            cases, the debugger will detect attempts to mix
            Performance Analysis and Fix and Continue operations,
            and prevent them.

            Incident 245326

          +o The Fix and Continue feature is not supported for code
            compiled with the Delta/C++ (DCC) compiler. The current
            implementation does not detect this problem.

          +o Fix and Continue can only be used on ELF executables
            compiled in shared mode.  Fix and Continue is
            implemented by using the dynamic loader, which is not
            available in COFF or non-shared ELF executables.

            Incident 243574

          +o Fix and Continue is only supported on IRIX 5.3. In
            particular, Fix and Continue is not supported on IRIX
            5.2 and IRIX 6.x.

       5.2.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__F_i_x__a_n_d__C_o_n_t_i_n_u_e

          +o The Disassembly View has not been updated to work with
            the Fix and Continue feature. As a result, you will
            notice the following behavior when viewing a modified
            function in Disassembly View:

               +o The filename displayed is incorrect, and reflects
                 the name of the temporary file used by the Fix and
                 Continue mechanism.

               +o The assembly instructions are not interleaved with
                 the source code.

               +o The line numbers shown in Disassembly View do not
                 reflect the line numbers used in the rest of the
                 debugger (i.e., instead of "7.3", the Disassembly
                 View will say line "9").

            Incident 243635













                                  - 17 -



          +o The initialization value of local statics in C may not
            be modified.  If you make such a change, it will
            silently be ignored. Since you are permitted to add new
            local statics, you can accomplish a change of the
            initialization value using the following workaround:

            /* Original function */
            void f() {
               static int i = 0; /* oops. This should be -1 */
            }

            /* New function */
            void f() {
               static int i = 0; /* oops. This should be -1 */
               static int first_time = 1;
               if (first_time) {
                  i = -1;
                  first_time = 0;
               }
            }

            Incident 246306

          +o In C it is legal to call a function without declaring
            it, and later declare the function to be static. For
            example:

               main(){
                  f();
                  return 0;
               }

               static int f(){
               }

            Since the Fix and Continue feature will only compile
            "main", and since there is no declaration for "f", the
            compiler will assume that "f" is an external function,
            and there will subsequently by a "Load Error" in the
            Interpreter Message window since the runtime loader
            will be unable to find an external definition for "f".
            The workaround is to make sure the compiler knows that
            "f" is static when you use modify "main" during a Fix
            and Continue operation:

               main(){
                  static int f();
                  f();
                  return 0;
               }












                                  - 18 -



            Incident 246317

          +o When executing an older version of a function, you will
            see the most recent source in the source window.
            Consequently the line numbers, PC highlight, and
            breakpoints displayed may be on the wrong lines.

          +o If you open a source file using "Source:Open...", the
            source file is opened in "Editable" mode by default.
            This prevents Fix and Continue operations on the file,
            and you will see the "Fix+Continue" button grayed out.
            If you wish to use Fix and Continue on this file, use
            the "Source:Make Read Only" menu option. If you use
            "Source:Open..." to open a source file in which you
            have previously modified functions, the modified
            functions will not be highlighted while the source file
            is editable.

            If you save a file in which some changes were made
            using Fix and Continue, and some changes were made
            using "Source:Open...", confusion may occur.  You can
            workaround this by using "Source:Make Editable"
            followed by "Source:Make Read Only". Another workaround
            is to switch to some other file and then switch back to
            the current file. Switching back can be accomplished by
            making the process stop in the file or by using
            "Source:Open..." followed by "Source:Make Read Only".

            Incidents 243627, 243629, 248842

          +o If you are stopped in a program, and you modify a
            function which is not the one you are stopped in, after
            the "Parse And Load" completes your source is
            repositioned at the line on which you are stopped,
            rather than at the function you just modified.

            Incident 246739

          +o When a "Parse and Load" is performed, a compiler is
            invoked to compile the modified function. Before
            performing the compile, the compilation process will do
            a "cd" so that the compilation takes place in the same
            directory as the original file was compiled in. This
            "cd" operation does not currently take path remapping
            into account, so you will have problems when you
            attempt to use "Fix and Continue" on an executable
            which was built on a different machine. The workaround
            is to make sure that you use "Fix and Continue" on an
            executable in the same environment as the one it was
            built in.  Another alternative is to adjust the command
            line options on the compile command (using the Build











                                  - 19 -



            Environment window) so that they will work in the
            debugging environment.

            Incident 246189

          +o The Fix and Continue mechanism does not currently check
            to make sure that a file has not been modified after it
            was last compiled. If you modify a function using Fix
            and Continue, save the source back to its original
            file, and forget to rebuild your application after
            exiting the debugger, you will see unpredictable result
            if you re-enter the debugger and attempt to use Fix and
            Continue. For example, the debugger may think that
            function "f" is on lines 15 to 20, whereas your
            previous changes may have repositioned the function on
            lines 17 to 22. When you select "Fix+Continue:Edit" if
            you notice that the edit region does not cover the
            entire body of the function, you should exit the
            debugger and rebuild your application.

            Incident 245098

          +o If your original build compiled multiple files with a
            single command line, this same command line will be run
            when using Fix and Continue to modify a function in any
            of those files, causing unnecessary recompilations of
            the other files, and possibly erroneous results.  For
            best results, compile files one at a time using the -c
            option of the compiler.  If this is not possible, use
            the Build Environment view to modify the command line
            and remove all file names from it (Fix and Continue
            will add in the file actually being compiled
            automatically).

          +o When you use the "Fix and Continue->Edit" menu item,
            the region you are allowed to edit begins with the line
            containing the first "{" of your function.  This line
            would include the line containing the function and
            parameter declaration, for the coding style shown
            below:

               void f(int y){
                  /* .... */
               }

            In such cases, you should make sure you do not change
            the function name and parameter profile. The
            implementation does not currently check that you do not
            make such changes, but you may receive a message like
            this:












                                  - 20 -



               No reply from PCS;
               unknown error while loading dso for the modified function

            Incident 245299

          +o If a "stop exit" trap is placed in a function, and Fix
            and Continue is used on the function after hitting the
            exit trap, then if execution can continue in the new
            function, the PC is moved back to the beginning of the
            line (it is in the epilogue, at the "jr ra"
            instruction). This means the epilogue is re-executed.
            This could cause problems if the stack pointer has
            already been decremented, because now it will get
            decremented twice. Your program may occasionally work
            if the stack decrement happens to be after the "jr ra"
            instruction. The implementation currently does not
            always detect this condition.

            The workaround is to reposition the PC at the "jr ra"
            using PC->JumpTo after your F&C has completed.

            F&C and templates

          +o Using F&C on functions which use templates are not
            completely supported in this release. Typically, if the
            change involves instantiating new functions, then such
            a  change is not supported in this release. If the
            process is stopped when this change is made, the F&C
            error message window will display the error message
            from rld under the PCS error messages. Otherwise, views
            would temporarily show that the change is ok, but when
            the process is run later , load error message will be
            reported and the change is switched back to edited
            state.

            The error message would be something like:  :
            26095:/tmp_mnt/hosts/xanadu/usr/people/pal/kim/mnm:
            rld: Fatal Error: unresolvable symbol in
            /var/tmp/cvintp26042/cvfn1.3.so:
                    static_allocator__15vector__pt__2_i

            Incident 249309


       5.3  _W_o_r_k_S_h_o_p__M_o_t_i_f__A_n_a_l_y_z_e_r

          +o The Motif Analyzer requires IRIX 5.3 or later for
            correct operation.  The instrumented libraries have
            been tested on older versions of IRIX and may result in
            compatibility problems with other shared libraries.












                                  - 21 -



          +o The Motif Analyzer may produce unexpected results when
            used with an application compiled on a pre-IRIX 5.3
            system using static libraries, and with non-Motif (e.g.
            Xaw) applications.  In particular, the widget selection
            and widget tree functionality may not work.

          +o The instrumented, debug Motif library shipped with the
            MegaDev.sw.motif subsystem and installed in
            /usr/lib/WorkShop/Motif contain the IRIX 5.3 version of
            motif_eoe.sw.eoe up to and including patch 258.  If you
            are debugging a Motif-related problem in your
            application and the problem is not reproducible using
            the instrumented Motif library in
            /usr/lib/WorkShop/Motif, it may be fixed with the patch
            258 version of motif_eoe.sw.eoe.

          +o If you create traps in the Motif Analyzer window using
            the Breakpoints examiner, trap items will appear in the
            Trap Manager window of the WorkShop Debugger.  These
            items will be labeled "MotifBreak."  You should not
            attempt to modify or delete these traps using the Trap
            Manager.  Instead, always use the Breakpoints examiner
            to modify or delete your Motif-related breakpoints.

          +o If you install the MegaDev.sw.motif subsystem and then
            reinstall the WorkShop.sw.cvd subsystem, the "Motif
            Analyzer" item will disappear from the Views menu in
            the WorkShop Debugger.  Reinstalling the
            MegaDev.sw.motif subsystem will correct the problem.

          +o If you install the WorkShop.sw.cvd and MegaDev.sw.motif
            subsystems, and then remove only the MegaDev.sw.motif
            subsystem, the "Motif Analyzer" menu item will still
            exist in the Views menu in the WorkShop Debugger.
            Selecting this menu item, however, will result in an
            error dialog.  Reinstalling the WorkShop.sw.cvd
            subsystem will remove the item from the Views menu.

          +o Occasionally, the Motif Analyzer display will remain
            inactive after switching between processes using
            WorkShop's "Switch Process" or "Switch Executable" menu
            items, or when rerunning the process after changing the
            command arguments.  If this happens, close the Motif
            Analyzer window and use WorkShop's Views menu to bring
            it up again.

          +o If your application connects to a remote X display and
            you do not set LD_LIBRARY_PATH to include
            /usr/lib/WorkShop/Motif, any Editres-type operations
            (e.g. widget select and widget tree) will operate on
            the local display and not work correctly.  Either run











                                  - 22 -



            your program using the local X display or change
            LD_LIBRARY_PATH as advised.

          +o A small number of applications build their widget
            hierarchy in such a way that Editres widget selection
            operations cause them to exit with an X error.  If your
            application falls into this category, then using the
            Motif Analyzer widget select functionality will cause
            the same thing to happen.


       5.4  _W_o_r_k_S_h_o_p__B_u_i_l_d__A_n_a_l_y_z_e_r

       If target or dependency names are specified using
       parentheses to denote files stored within an archive
       library, _c_v_b_u_i_l_d will use a single node to represent the
       archive library, rather than individual nodes for each file
       within it.


       5.5  _W_o_r_k_S_h_o_p__S_t_a_t_i_c__A_n_a_l_y_z_e_r

       5.5.1  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s

          +o The Directory Query "List Files" works only when the
            query target is a full path name of a directory.  For
            example, it works on the target "/usr/include", but not
            on a target like "include".

            Workaround: Select the General Option "Full Pathnames".
            Then any directory names displayed will contain full
            paths, and so the "List Files" query will cork on them
            correctly.

          +o If you use _c_v_s_t_a_t_i_c to analyze a fileset and then
            change one or more of the header files included by the
            files in the fileset, rescanning the fileset will not
            detect the change.  Rescanning only detects changes to
            source files listed in the fileset.  Similarly, if you
            remove a source file from a fileset and rescan, the
            header files included by that file are not removed from
            the database. (Incident #179731)

            Workaround: If you have changed one or more files in a
            fileset (or included by files in a fileset), you can
            get a consistent database by selecting ``Force Scan''
            from the Admin menu.

          +o Some printers may clip the output when printing a
            PostScript version of graph saved by _c_v_s_t_a_t_i_c.












                                  - 23 -



            Workaround: None, except trying another printer, or
            re-laying out the graph by hand to avoid clipping.

       5.5.2  _K_n_o_w_n__P_r_o_b_l_e_m_s__w_i_t_h__M_i_x_e_d__L_a_n_g_u_a_g_e_s

          +o If you analyze a program that contains both Fortran and
            C routines, _c_v_s_t_a_t_i_c in scanner mode does not recognize
            that the C function ffffoooooooo____ and the Fortran function ffffoooooooo
            refer to the same routine.  In parser mode, _c_v_s_t_a_t_i_c
            will identify the routines correctly, if it analyzes
            the C file containing ffffoooooooo____ before the Fortran file that
            calls ffffoooooooo.  So, make sure that your C files appear
            earlier in the fileset than your Fortran files.

















































                                  - 24 -




       5.5.3  _G_e_n_e_r_a_l__K_n_o_w_n__P_r_o_b_l_e_m_s__i_n__S_c_a_n_n_e_r__M_o_d_e

          +o In general, _c_v_s_t_a_t_i_c does not require code to be able
            to be compiled.  _c_v_s_t_a_t_i_c should provide useful
            information even when code has syntax errors. However,
            there are several requirements that must be met for
            _c_v_s_t_a_t_i_c to work properly. In C and C++, _c_v_s_t_a_t_i_c
            relies on the existence of matching braces to determine
            the beginning and ending of blocks and bodies of
            functions. In Fortran, _c_v_s_t_a_t_i_c relies on the existence
            of matching end statements. Functions without closing
            braces, or end statements, or code with too many end
            statements or mismatched braces can cause unpredictable
            results. In C, it may be necessary to use _c_v_s_t_a_t_i_c's
            ----pppprrrreeeepppprrrroooocccceeeessssssss option with heavily _i_f_d_e_f'd code to achieve
            matched braces.

            If any of these limitations of scanner mode keeps
            _c_v_s_t_a_t_i_c from being useful, using parser mode may be
            the right solution.

          +o _c_v_s_t_a_t_i_c accepts regular expressions in nearly all
            fields. This can occasionally cause problems if you
            unintentionally use a pattern without realizing it is a
            regular expression. For example, specifying a filename
            of ffffoooooooo....cccc++++++++ usually fails, because ++++ is a special
            character in regular expressions.

            Workaround: Backslash all regular expression special
            characters when not used to specify a wildcard pattern.
            For example, the filename mentioned above would be
            entered as ffffoooooooo....cccc\\\\++++\\\\++++.

          +o The _c_v_s_t_a_t_i_c Variable query, ``Who Sets'' recognizes
            only variable assignments that use ``='' to assign
            directly to a variable.  This query does not recognize
            or account for aggregate initialization statements in C
            or C++, references in C++, assignments made as a result
            of passing or operating on pointers in C, or data,
            equivalence, common, or assign statements in Fortran.

            Workaround. Use ``Who References'' to see all locations
            in which the variable is used and to visually inspect
            for assignments.

          +o By default, _c_v_s_t_a_t_i_c does not honor _i_f_d_e_f's in source
            code. Much of the time, this is desirable behavior.
            _c_v_s_t_a_t_i_c allows you to find _a_l_l references that satisfy
            a query. However, this may result in an incorrect or
            misleading function call tree. Heavily _i_f_d_e_f'd code may











                                  - 25 -



            also confuse _c_v_s_t_a_t_i_c, because (in C) _c_v_s_t_a_t_i_c relies
            on matching braces to detect the end of functions.

            Workaround: Use the ----pppprrrreeeepppprrrroooocccceeeessssssss flag when starting
            _c_v_s_t_a_t_i_c. This makes _c_v_s_t_a_t_i_c run much more slowly, but
            it honors most _i_f_d_e_fs.

          +o _c_v_s_t_a_t_i_c recognizes many common C, C++, and Fortran
            language patterns.  However, all three languages allow
            programmers to write code that is not easily identified
            by patterns.

            Workaround: If you find that _c_v_s_t_a_t_i_c misses or
            misidentifies parts of a program, you can usually
            resort to string, regular expression, or symbol queries
            to find the information you are looking for.

          +o Files containing very long lines are not handled in
            scanner mode. If a file contains any line longer than
            3000 characters, _c_v_s_t_a_t_i_c's scanner will fail.

            Workaround: Use parser mode, or shorten your source
            lines.

       5.5.4  _K_n_o_w_n _P_r_o_b_l_e_m_s _U_s_i_n_g _c_v_s_t_a_t_i_c _i_n _S_c_a_n_n_e_r _M_o_d_e _w_i_t_h
       _C++  _c_v_s_t_a_t_i_c analyzes C++ source code much more accurately
       in parser mode than in scanner mode.  The following problems
       are known to occur in scanner mode.  They can be avoided by
       following the workaround suggestions, or by using parser
       mode.

          +o _c_v_s_t_a_t_i_c does not do macro expansion, so classes based
            on macros used to simulate C++ parameterized types are
            not detected.

          +o _c_v_s_t_a_t_i_c does not completely handle function calls made
            through function pointers, in C or C++. In C++, this
            includes calls to member functions made through object
            pointers.  For example, consider the following code
            segment:

            ssssaaaammmmpppplllleeeeffffuuuunnnnccccttttiiiioooonnnn (((())))
            {{{{
               AAAA ****oooobbbbjjjjeeeecccctttt1111 ==== nnnneeeewwww AAAA(((())));;;;
               BBBB ****oooobbbbjjjjeeeecccctttt2222 ==== nnnneeeewwww BBBB(((())));;;;
               oooobbbbjjjjeeeecccctttt1111---->>>>ffffuuuunnnncccc(((())));;;;
               oooobbbbjjjjeeeecccctttt2222---->>>>ffffuuuunnnncccc(((())));;;;
            }}}}

            In this example, _c_v_s_t_a_t_i_c correctly reports that
            samplefunction() calls func() two times. However, it











                                  - 26 -



            cannot determine that these two function calls are
            actually made to two different member functions,
            implemented by two different classes. Similarly,
            _c_v_s_t_a_t_i_c does not know about the _t_h_i_s pointer.

            Workaround: Don't try to display full function call
            trees for C++. Instead use queries like ``Who Calls
            <function>''or ``Who Is Called By <function>'' which
            produce meaningful results.

          +o _c_v_s_t_a_t_i_c does not understand overloaded functions.

            Workaround: Use the text view for all queries involving
            overloaded functions.

          +o C++ allows extensive use of operator overloading, which
            allows you to write code that can obscure what is
            really happening in the code. Because _c_v_s_t_a_t_i_c is
            designed around a pattern matcher, novel constructs
            produced by overloading operators are not normally
            detected. Constructs that conform to normal language
            conventions should normally be found. For example, if A
            and B are objects, and the ``='' operator has been
            overloaded to indicate an assignment of the contents of
            object B to the contents of object A, _c_v_s_t_a_t_i_c should
            be able to handle this situation. However, if some
            unusual overloading conventions have been used (say,
            using ``[]'' to mean a function call), _c_v_s_t_a_t_i_c does
            not show the same results as the C compiler.

            Workaround: If you have such code, use string or
            regular expression searches, or symbol searches to find
            what you are looking for.

          +o C++ programs containing templates are not well
            understood by scanner mode.

            Workaround: Use parser mode.

       5.5.5  _K_n_o_w_n__p_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__w_i_t_h__F_o_r_t_r_a_n

          +o Problem: cvstatic changes case in source files.

            Workaround:  For best results, ignore case:

            Because the Fortran compilers translate Fortran
            programs to lower (for Fortran 77) or upper (for
            Fortran 90) case when analyzing them, you may have
            trouble selecting a symbol name from the Source View
            and then using the selection as the target of a query.
            Therefore, when using the Static Analyzer on Fortran











                                  - 27 -



            sources, it is best to select the Ignore Case option,
            either through the General Option menu, or persistently
            through the use of the X resource mechanism thus:

                    cvstatic*ignoreCase: True

          +o Problem: Fortran file suffixes are ambiguous.

            Workaround: Tell cvstatic what suffixes you use for
            which Fortran variant.

            Both Fortran 77 and Fortran 90 accept files with the
            the suffixes .f and .F.  So, there is no obvious way
            for the Static Analyzer to tell whether a source file
            is Fortran 77 or Fortran 90.

            To indicate that you want a particular suffix to
            correspond to a particular language, you can set the
            suffixSource X resource before running cvstatic.  For
            example:

            *suffixSource: C++.c++ C++.C C++.cxx C++.h C.c
            Fortran.f Fortran90.F Fortran90.f90

            This line in your .Xdefaults file indicates that you
            want files ending .f to be analyzed as Fortran 77
            codes, while files ending .F or .f90 are Fortran 90.

            You may want to analyze a set of files in which some
            files ending .f are Fortran 77 while other files with
            the same suffix are Fortran 90.  If so, the only way to
            distinguish them is for you manually to edit the
            cvstatic.fileset file and make sure that each filename
            is followed by the correct driver.  For example, these
            two lines in the fileset file indicate that foo.f is a
            Fortran 77 file, while bar.f is Fortran 90:

                ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////ffffoooooooo....ffff ffff77777777
                ////uuuussssrrrr////ppppeeeeoooopppplllleeee////yyyyoooouuuu////bbbbaaaarrrr....ffff ffff99990000

       _c_v_s_t_a_t_i_c analyzes Fortran source code much more accurately
       in parser mode than in scanner mode.  The following problems
       are known to occur in scanner mode.  They can be avoided by
       following the workaround suggestions, or by using parser
       mode.

          +o _c_v_s_t_a_t_i_c occasionally misses function calls and other
            statements that directly follow an _i_f statement on the
            same line.













                                  - 28 -



          +o _c_v_s_t_a_t_i_c uses a pattern matching approach. This
            approach does not allow the tool to detect the
            irregular use of spaces within Fortran symbols, even
            though these are allowed by the Fortran compiler. For
            example, the Fortran compiler accepts the statement:

                   ssssuuuubbbb rrrroooouuuuttttiiiinnnneeee mmmmyyyy
                  1111ffffuuuunnnncccc ttttiiiioooonnnn

            as if it were written:

                  ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee mmmmyyyyffffuuuunnnnccccttttiiiioooonnnn

            _c_v_s_t_a_t_i_c does not handle such conventions.

            Workaround: None in scanner mode. Silicon Graphics
            strongly suggests changing such code to use a more
            readable coding style.

          +o _c_v_s_t_a_t_i_c does not support the use of Fortran keywords
            for uses other than their intrinsic function. For
            example, _c_v_s_t_a_t_i_c always recognizes word ``if'' as
            starting a conditional statement. Programs that use
            ``if'' as a variable or function name are not analyzed
            correctly.

            Workaround: None in scanner mode. Silicon Graphics
            strongly suggests changing such code to use a more
            readable coding style.

          +o In some situations, _c_v_s_t_a_t_i_c can mistake references to
            arrays as function calls. This is particularly true
            when the Fortran code relies on include files to
            declare arrays, common blocks, and so on. _c_v_s_t_a_t_i_c does
            not analyze header files at the point at which they
            occur, but simply adds them to the list of files to be
            analyzed. This contributes greatly to the speed of
            _c_v_s_t_a_t_i_c, but means that _c_v_s_t_a_t_i_c does not have various
            type declarations available to it. Because Fortran
            arrays cannot be differentiated from function calls
            without a declaration, _c_v_s_t_a_t_i_c identifies arrays not
            defined in the file in which they are referenced as
            function calls.

            Workaround: Use the Results Filter to exclude
            ``external'' functions. This limits all queries to
            those functions actually defined in the fileset.
            Excluding external functions hides all array references
            erroneously identified as function calls, but also
            hides all calls to library functions, intrinsic
            functions, or other routines declared outside the











                                  - 29 -



            fileset.

       5.5.6  _K_n_o_w_n__P_r_o_b_l_e_m_s__U_s_i_n_g__c_v_s_t_a_t_i_c__i_n__P_a_r_s_e_r__M_o_d_e
            Sometimes the General query "Where Symbol Used" fails
            to report some call sites, if the target of the query
            was a function.

            WorkAround: Use the Function query "Who Calls" or
            "Where Function Used" to get a complete list of places
            wehre the target function is called or otherwise used.

          +o The query Where Type Used may return duplicate results
            in C and C++ programs.  For example, asking Where Type
            Used Foo will produce two copies of the result showing
            the definition of the symbol

                       FFFFoooooooo ffff;;;;

            If one of these locations is shown without a function
            field and one is shown with a function, the latter is
            correct.

            Workaround: If you are explicitly looking for
            definitions, use the queries List Data of Type or List
            Functions of Type instead.  Otherwise, just ignore the
            duplications.

          +o The query Where Type Used is confusing about pointers
            in C and C++.

            If you ask Where Type Used about a user-defined type
            named Foo, the query will display all uses of Foo,
            including uses of types like Foo*, Foo**, Foo[], etc.

            But if you ask Where Type Used about a built-in type
            like void or char, the query will display only uses of
            that exact type.

            Workaround: Query explicitly about typenames like
            void*, char**, etc, that contain no user-defined
            typenames.

          +o Queries on "integer" and "real" in fortran don't work.

            Fortran reports integer types as having typenames I*4
            and I*8, real types with typenames R*4, R*8, complex
            types with typenames CM*8 and CM*16, and logical types
            as L*4.

            Workaround: To inquire about uses and declarations with
            these types, enter I*4 (or whatever) into the target











                                  - 30 -



            field instead of "integer".

          +o Mismatched member function declarations and definitions
            are not recognized by _c_v_s_t_a_t_i_c'_s parser.  The parser
            runs into trouble processing a member function if the
            signature of its declaration and definition are not
            identical.  For example, if the code contains something
            like this:

            ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt**** iiiinnnnttttppppttttrrrr;;;;

            ccccllllaaaassssssss AAAA {{{{
            ppppuuuubbbblllliiiicccc::::
                AAAA ((((iiiinnnntttt **** iiii))));;;;
            }}}};;;;

            AAAA::::::::AAAA ((((iiiinnnnttttppppttttrrrr iiii)))) {{{{
            }}}}

            the parser will print the error message "no record for
            method A::A?" and terminate processing of the file.

            Workaround: analyze code like this in scanner mode, or
            change the type signatures so that the definition and
            declaration match.

          +o _c_v_s_t_a_t_i_c's parser mode is better at building a new
            database than at modifying an existing one.  If you
            build a parser-mode database and then change a file and
            reparse it, the database will grow each time you rescan
            the file.  Not all space is reclaimed.  Additional arcs
            may appear in the Call Tree view representing defunct
            call site information.

            Workaround: After a few files are modified and re-
            analyzed, it is best to use Force Scan to rebuild the
            entire parser-mode database. For a large code base that
            is slow to parse, you can use the -batch flag to
            rebuild the database overnight.

          +o Functions generated by templates are recognized and
            displayed by _c_v_s_t_a_t_i_c, but it treats them as external
            functions:  functions that are declared or used within
            the fileset but are not defined there. Consequently,
            they do not appear in the results of the ``Query List
            All Functions''.

            Workaround: Use specific queries about these functions,
            like ``Where Function Called'', or add them manually to
            Call Tree graphs.












                                  - 31 -



          +o The function "main" appears in the list of Functions
            Not Called, if it is not called explicitly from the
            source code.  ("main" is rarely called explicitly.)

            Workaround: You can add the function "main" manually to
            any graphical display of functions.

          +o Graphical display of a single member function called
            through derived classes is incomplete.  If a C++ member
            function FFFFoooooooo::::::::FFFFuuuunnnncccc is called through classes derived
            from the ccccllllaaaassssssss FFFFoooooooo, each derived function FFFFuuuunnnncccc will
            appear as a separate function in the Text View list of
            functions.  However, only one node will appear for FFFFuuuunnnncccc
            in the Call Tree View.

            Workaround: To see the full list of definitions and
            calls of FFFFuuuunnnncccc, use Text Mode.  If you double click on
            the definition of one of the derived FFFFuuuunnnnccccs, you will
            navigate either to the definition of the function (if
            you click on the version in FFFFoooooooo), or to the definition
            of the derived class through which FFFFuuuunnnncccc was called.

          +o If you are analyzing C++ code in which multiple non-
            member functions have the same name, _c_v_s_t_a_t_i_c will
            think they are all the same function with one
            definition and several declarations.

            Workaround: You can get to the definitions by using the
            ``Where Defined'' and ``Where Declared'' queries on
            functions.

          +o When you first bring up _c_v_s_t_a_t_i_c, if you switch the
            view from Text View to a graph view before building the
            parser database and doing your first query, the graph
            may incorrectly display as empty.

            Workaround:  Stay in Text View to perform your first
            query, and then switch to whichever graph view you
            wish.  Or, if you have already brought up _c_v_s_t_a_t_i_c in a
            graph view and built the database, hit ``Rescan'' in
            the Admin menu, and then redo your query.


       5.6  _W_o_r_k_S_h_o_p__C_+_+__B_r_o_w_s_e_r

          +o The _C++ _B_r_o_w_s_e_r currently works only on files in the
            parser fileset.  So if you have a fileset which has
            only files in the scanner fileset, the browser will not
            work. To generate the database, you have to put files
            in the parser fileset and issue a rebuild in _c_v_s_t_a_t_i_c.
            Once the database is created you can use Browser to











                                  - 32 -



            examine the C++ classes.

          +o When using the C++ Browser, if you make changes to the
            code in the files that are present in the fileset, the
            changes will not be reflected in the information
            presented by the C++ Browser until you issue a Rescan
            command in _c_v_s_t_a_t_i_c, as follows:

            *    Make your changes.

            *    Exit the C++ Browser (but not cvstatic).

            *    Issue a FFFFoooorrrrcccceeee SSSSccccaaaannnn from the cvstatic AAAAddddmmmmiiiinnnn menu.

            *    Restart the browser by selecting AAAAddddmmmmiiiinnnn/CCCC++++++++ BBBBrrrroooowwwwsssseeeerrrr
                 menu in cvstatic.

            Incident 186990.

          +o When using the C++ browser, if you create and close (or
            quit) the Class Graph or Call Graph windows many times,
            some times you may find that it will make the tool core
            dump or exit with X errors. This is due to some known
            defects in deletion of widgets in Xm and Sgm.

            Incident 204472.

          +o Duplicate class definitions encountered in your files
            in the parser fileset will end up as a single class
            with accumulating members from both the definitions.
            This happens when the file defining the class is
            included from two different paths or there are two
            genuine class definitions for the same class name in
            your fileset.

            Incident 206922.

          +o If you use typedefs, and use it to give alternate names
            to classes (as in _t_y_p_e_d_e_f _c_l_a_s_s _A _B;) - you may that
            the Build Window shows some warnings about not finding
            the class B and that the information collected about
            the usage of class A will be missing many of the
            references through its typedef B.

            This kind of typedef is more commonly found in template
            code. There is no good workaround currently, other than
            not using the typedef in question.

            Incident 217830.













                                  - 33 -



          +o If you use typedefs, and use it inconsistently in
            declaring and defining class members (as in the
            following example), you will find that information
            regarding those members is either missing or faulty.
            The workaround is to use the same prototype at the
            point of definition as at the point of declaration.

                ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt IIIINNNNTTTT;;;;
                ccccllllaaaassssssss AAAA {{{{
                   vvvvooooiiiidddd ffffoooooooo ((((IIIINNNNTTTT))));;;;
                }}}};;;;

                vvvvooooiiiidddd AAAA::::::::ffffoooooooo ((((iiiinnnntttt vvvvaaaallll)))) ............   //////// ggggeeeettttssss wwwwaaaarrrrnnnniiiinnnngggg,,,, aaaannnndddd iiiissss mmmmiiiissssssssiiiinnnngggg
                                            //////// ffffrrrroooommmm ssssttttaaaattttiiiicccc aaaannnnaaaallllyyyyssssiiiissss iiiinnnnffffoooo....

            Incident 184455.

          +o Usage information for template classes is managed only
            on a per-instantiation basis.  If you use templates in
            your code, then each instantiation, and the template
            itself, will show up as classes in the C++ Browser.

            For instance, if you have a template class Foo<T>, then
            there will be a class called FOO<T> and classes FOO<A>,
            FOO<B> etc., for the template definition prototype of
            FOO and its instantiations with A, B, etc.,
            respectively. And the usage information on FOO<T>
            currently shown is not the amalgamation of usage
            information on its instantiations FOO<A>, FOO<B>, etc.

          +o Be careful about overwriting man pages which are
            generated using the automatic class man page generation
            facility.

            When you generate a manpage for a class, through the
            C++ browser, you get a skeleton, in which you have to
            fill in all the descriptions. Please remember that if
            you change the class and generate a new man page for
            that class again, your changes to the file will be lost
            if you ignore the man page overwrite warning dialog.

            To avoid losing your changes to a manpage file
            generated by C++ Browser do the following:

            *    Move the existing manpage out of the way to some
                 other file.

            *    Generate the new (skeleton) man page.

            *    Merge the changes from the saved file to the new
                 man page generated by the C++ Browser.











                                  - 34 -



          +o When you use an application which allocates lot of
            colors in the default color map and then use cvstatic
            or C++ browser to bring up graphs, you might get all
            black nodes with un-readable text. The only known
            workaround to this problem is to kill the X server and
            login again. Be sure that you bring up cvstatic before
            you bring up the offending application. This problem
            has been seen with viewing books which have full color
            pictures.


       5.7  _W_o_r_k_S_h_o_p__P_e_r_f_o_r_m_a_n_c_e__A_n_a_l_y_z_e_r

          +o On some systems with 16K or larger pages size, some
            versions of libXm.so.1 when instrumented for PC
            sampling, can not be loaded.  Try using SpeedShop's PC
            sampling instead (Incident #515045).

          +o On some systems, libgl.so will crash when instrumented
            for PC sampling.  Try using SpeedShop's PC sampling
            instead (Incident #515048).

          +o _c_v_p_c_s may core dump when profiling Ada applications
            (Incident #478331).

          +o Instrumentation may generate an incorrect file name for
            instantiated templates from C++ (Incident #284412).

          +o Ideal-time and CPU-time experiments on programs that do
            dlopen's may fail on R5K Indy machines, due to a HW bug
            that causes traps to be missed the first time through.
            The recording of performance experiments relies on an
            internal trap to dlopen in order to instrument the DSO
            being dlopen'd (Incident #439770).

          +o Total-time and bottleneck experiments will overcount
            inclusive time for recursive functions (Incident
            #438591)

          +o Running the Bottleneck and Total-Time experiments
            significantly slow the execution of some programs
            because of the time it takes to unwind the stack.

          +o _c_v_p_e_r_f is not backwards-compatible with experiments
            recorded on prior WorkShop releases, and will typically
            core dump on them.

          +o Instrumenting _l_i_b_c with the PC-sampling option will
            fail in IRIX 5.3 because there is not enough address
            space left for text and data sections (Incident
            #223912).  These experiments work in IRIX 6.2 or later.











                                  - 35 -



            Workaround:  There is no workaround for this problem on
            IRIX 5.3.

          +o Memory leak experiments on programs that fork may
            produce misleading data.  For example, a child process
            may free a block allocated in the parent, which will
            appear as a bad free.  (Incident #202710)

          +o During data collection, the collector, _c_v_m_o_n, might run
            out of disk space.  In this case, it posts an error
            pop-up to the effect of ``bead write failed: no space
            left on device''.

            Workaround: Exit the debugger, free up sufficient space
            on the disk, and start the run again.

          +o The Performance Analyzer does not support COFF
            executables.

          +o The Performance tools can collect a great deal of data,
            and easily fill a disk.  For typical programs, basic-
            block sampling can collect between 0.25 and 2 Mbytes of
            data at each sample point.  PC sampling data can amount
            to between 0.25 and 6 Mbytes for each sample.

            Workaround: Use care in specifying how many samples you
            take to avoid this problem.  Be especially careful in
            using Pollpoint sampling; it should normally be used
            collecting only callstacks, not function counts,
            basic-block counts, or PC sampling data.  Sampling is
            not expensive in tracing experiments.

          +o The Main View has a notion of a default trap that is a
            stop trap if data collection has not been enabled in
            the Performance Panel (where ``enabled'' means after
            _A_c_c_e_p_t or _O_K was clicked), and a sample trap if it has
            been enabled.  This setting is independent of the
            default trap set in the Trap Manager.  Clicking in the
            margin of the MainView source window sets or clears the
            MainView default trap, and does not affect a trap of
            the other type.

          +o _m_a_l_l_o_c/_f_r_e_e traces can be quite voluminous and
            difficult to process in Heap View.  When doing
            _m_a_l_l_o_c/_f_r_e_e tracing, be careful to design your
            experiments to exercise only those regions of your code
            that are problematic, and minimize the amount of trace
            data collected.  It is difficult to estimate the volume
            of data produced.  Each event writes 20 to 80 bytes, or
            more, depending on the depth of the callstack at the
            time of the call. A 10-minute experiment with the











                                  - 36 -



            WorkShop Performance Analyzer wrote 140 Mbytes of trace
            data.  Reading this experiment took ~12 minutes on a
            256-MB Onyx machine.

          +o The WorkShop Performance Analyzer can record
            experiments on MP FORTRAN programs, but there are a
            number of anomalies in the displayed data that require
            explanation.  For all FORTRAN MP compilations, parallel
            loops within the program are represented as subroutines
            with names relating to the source routine in which they
            are embedded.  The naming conventions for these
            subroutines are different for o32-bit, N32, and 64-bit
            compilations.  In the linpack benchmark, most of the
            time spent is in the source routine _D_A_X_P_Y, which can be
            parallelized.  The MP loop-body routines are invoked
            indirectly from the original function, and will show up
            as directly calls from a routine name __mp_parallel_do.

            When compiled with the 7.2 compilers, in either 64-
            bits, or n32, the MP loop-body routine is named
            "__mpdo_daxpy_1", and the function is named "daxpy_".
            However, there is a test in the compiled loop to
            determine if the work to be done is sufficient to be
            worth running in parallel.  That means if the test
            succeeds, time will be shown in the routine
            __mpdo_daxpy_1, while if the test fails, the time will
            be recorded in the routine daxpy_.

            In an o32-bit version, the _D_A_X_P_Y routine is named
            "daxpy_", and the MP loop body routine
            "_daxpy_519_aaab_".

            In all three cases, for an ideal time experiment on a
            uniprocessor -_g run, the inclusive and exclusive
            function level times are correct.  The source
            annotations, however, behave differently and
            incorrectly in most cases.

            With the 7.2 or 6.x compilers, source annotations for
            the exclusive time are correctly shown for each line,
            but the inclusive time for the first line of the loop
            (_d_o statement) includes the time spent in the loop
            body. This same time appears on the lines comprising
            the loop's body, in effect, representing a double-
            counting.  When used in conjunction with WorkShop Pro
            MPF's Parallel Analyzer View, the loop performance data
            will incorrectly also reflect the double counting, and
            the time will not be always shown as a percentage:
            whenever it would exceed 100%, it is shown as <_n/_a>.
            The numerical time value shown reflects the double
            counting.











                                  - 37 -



            In 32-bit source annotations, the exclusive time is
            incorrectly shown for the line comprising the loop's
            body, as the line-level data for the loop-body routine
            ("_daxpy_519_aaab_") does not refer to proper lines.
            If the program was compiled with the -_m_p__k_e_e_p flag, the
            line-level data should refer to the temporary files
            that are saved from the compilation, but the temporary
            files do not contain that information, so no source or
            disassembly data can be shown.  The disassembly data
            for the main routine does not show the times for the
            loop-body.

            If the 32-bit program was compiled without -_m_p__k_e_e_p,
            the line-level data for the loop-body routine is
            incorrect, with most lines referred to line 0 of the
            file, and the rest to other lines at seemingly random
            places in the file.  Consequently, spurious annotations
            will appear on these other lines.  Disassembly
            correctly shows the instructions, and their data, but
            the line numbers shown are wrong.  MPF's Parallel
            Analyzer correctly shows the loop data in most cases,
            but the same incorrect line numbers can cause data
            relating to one loop to show up in other parts of the
            program.  This reflects what is essentially the same
            double-counting problem as seen in 64-bits, but the
            extra counts go to other places in the file, rather
            than the first line of the loop.

            NNNNOOOOTTTTEEEE:::: We recommend against using the -_m_p__k_e_e_p flag.

          +o For MP experiments, switching between threads will
            cause the calipers to change to points valid for the
            new thread. Switching back may use different points,
            and therefore, show different numbers. Set the calipers
            manually after switching to ensure proper placement.

          +o For MP experiments, stopping one thread can cause the
            notion of time in other threads to get confused.  It is
            not recommended.

          +o The inclusive data shown in _c_v_p_e_r_f represents the
            instruction counts and/or PC sampling data summed over
            the routine and those routines that it calls.  The
            computations are based on a heuristic that assumes that
            all calls from all callers are equivalent.  For
            programs where this heuristic is not applicable, for
            example, where one call to a matrix-multiply routine is
            for matrices of order four, while a second call is for
            matrices of order 100, the cumulative data may be
            misleading.












                                  - 38 -



          +o Line-level data assigns a value to a line equal to the
            highest value for any instructions attributed to that
            line.  It can be confusing, because compiler
            optimizations often rearrange the code in ways that is
            non-obvious.  Looking at a disassembly view of the data
            can help.

          +o Line-level data from assembler routines can be
            misleading.  The symbol table often has instructions
            attributed to the wrong source line.

          +o In some cases, line number data for a C++ routine that
            uses inline virtual functions defined in an included
            file gets the line numbers incorrectly displayed as if
            they came from the file in which the defining file is
            included.  This causes incorrect line-level data to
            show at the lines in the original file.  The
            Disassembly View in _c_v_p_e_r_f shows performance data for
            each instruction, and may help disambiguate attribution
            (Incident #433284).

          +o _c_v_p_e_r_f filters out nodes and arcs that were not
            executed during the current caliper setting.  This
            feature can lead to confusing displays, where nodes
            that are known to be in the program do not appear.

            Workaround: The Preferences menu can be used to disable
            the filtering.

          +o _c_v_p_e_r_f does not support live performance experiments.
            That is, you should not bring up _c_v_p_e_r_f until the
            experiment is over.  If you do, it will not update as
            more data is recorded.

          +o Performance experiments on multi-process applications
            can occasionally be unreliable if sample events are
            quickly preceded by process creation, or succeeded by
            process termination.

          +o Heap View scrolls poorly and blocks flash on large
            experiments.  Its functionality has been mostly
            subsumed by Leak View, Malloc View, and Malloc Error
            View.  (Incident# 67628)

          +o Callstacks may be wrong in MP experiments.  (Incident#
            189826)

          +o Pollpoint sampling will fail if the target process
            forks, and the parent exits before the child.
            (Incident #186429)












                                  - 39 -



          +o The Performance Analyzer can dump core when computing
            line-level annotations on o32 programs.

            Workaround: Exit _c_v_d and call _c_v_p_e_r_f directly.


       5.8  _W_o_r_k_S_h_o_p__T_e_s_t_e_r

       5.8.1  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__L_i_m_i_t_a_t_i_o_n_s

          +o Instrumented programs can increase in size by a factor
            of 2X to 5X.  However, DSO caching and sharing
            alleviates this problem greatly.

          +o Block and branch coverage are at the assembly language
            level.  They can provide useful metrics and do map back
            to the source lines.  Note that several assembly branch
            instructions may map back to the same source line.  To
            see the C, C++, and Fortran source level blocks and
            branches, use _c_v_c_o_v _l_s_s_o_u_r_c_e.

          +o Compilation with the debug flag -_g builds assembly
            language branches and blocks that can never be
            executed.  This adversely affects overall coverage.  By
            compiling with "O1" (the default), some of the unused
            assembly branches and blocks are not built.  This gives
            a more accurate block and branch coverage metric.
            Function and arc coverage are unaffected by compile
            flags.

          +o C++ in-line functions are not counted as functions
            unless they are out-of-lined by the compiler.

          +o By default, arguments of functions are not displayed in
            query results.  This can be confusing for C++
            overloaded functions because there is no way to
            distinguish between them.  To work around this problem,
            use the -_a_r_g option to show full function signatures.

          +o The default size of the SourceView annotation canvas
            may not be large enough to hold very large counts.  The
            resource name for setting canvas width for SourceView
            is "canvasWidth".  The default value is 60.  The user
            can modify this width by modifying the following
            resource found in the Cvxcov app-defaults file,
            "Cvxcov*test*testData*canvasWidth".

          +o _T_e_s_t_e_r currently uses object level instrumentation.
            This has several advantages:

                ((((1111)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt aaaacccccccceeeessssssss ttttoooo tttthhhheeee











                                  - 40 -



                    ssssoooouuuurrrrcccceeee ccccooooddddeeee....
                ((((2222)))) CCCCoooovvvveeeerrrraaaaggggeeee ddddaaaattttaaaa ccccaaaannnn bbbbeeee oooobbbbttttaaaaiiiinnnneeeedddd wwwwiiiitttthhhhoooouuuutttt rrrreeeeccccoooommmmppppiiiillllaaaattttiiiioooonnnn////rrrreeeebbbbuuuuiiiilllldddd....
                ((((3333)))) TTTThhhhiiiissss ssssuuuuppppppppoooorrrrttttssss CCCC,,,, CCCC++++++++,,,, aaaannnndddd FFFFoooorrrrttttrrrraaaannnn wwwwiiiitttthhhhoooouuuutttt ssssppppeeeecccciiiiaaaallll
                    llllaaaannnngggguuuuaaaaggggeeee ssssuuuuppppppppoooorrrrtttt ffffrrrroooommmm tttthhhheeee ccccoooommmmppppiiiilllleeeerrrrssss....

            This has several disadvantages:

                ((((1111)))) BBBBlllloooocccckkkk aaaannnndddd bbbbrrrraaaannnncccchhhh ccccoooouuuunnnnttttssss aaaarrrreeee aaaatttt tttthhhheeee aaaasssssssseeeemmmmbbbbllllyyyy llllaaaannnngggguuuuaaaaggggeeee lllleeeevvvveeeellll....
                ((((2222)))) MMMMoooorrrreeee ddddeeeettttaaaaiiiilllleeeedddd ccccoooovvvveeeerrrraaaaggggeeee rrrreeeeqqqquuuuiiiirrrreeeessss kkkknnnnoooowwwwlllleeeeddddggggeeee ooooffff tttthhhheeee
                    llllaaaannnngggguuuuaaaaggggeeee sssseeeemmmmaaaannnnttttiiiiccccssss.... FFFFoooorrrr eeeexxxxaaaammmmpppplllleeee,,,, hhhhaaaassss eeeevvvveeeerrrryyyy ppppoooossssssssiiiibbbblllleeee ccccaaaasssseeee
                    iiiinnnn aaaa mmmmuuuullllttttiiiipppplllleeee ccccoooonnnnddddiiiittttiiiioooonnnnaaaallll ffffiiiirrrreeeedddd dddduuuurrrriiiinnnngggg tttteeeessssttttiiiinnnngggg....

          +o _W_e_a_k _e_x_t_e_r_n_a_l_s refer to an aliasing facility used by
            the compilation environment.  For example, while user
            programs may call the function "read", the actual
            function name in the C library that implements "read"
            is "_read". In this case, "read" is a weak external for
            "_read".  If the user CONSTRAINS coverage on either
            name, _T_e_s_t_e_r will report the results correctly.
            However, _T_e_s_t_e_r will choose the name used to implement
            the function, in this case "_read".

          +o -_f_u_n_c__p_a_t_t_e_r_n is a function pattern used in the
            following _c_v_c_o_v subcommands: _l_s_b_l_o_c_k, _l_s_b_r_a_n_c_h, _l_s_f_u_n,
            _l_s_t_r_a_c_e.  Currently, only the following "patterns" are
            matched.

                """"DDDDSSSSOOOO::::****""""              -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss iiiinnnn aaaa DDDDSSSSOOOO
                DDDDSSSSOOOO::::ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee    -------- ssssppppeeeecccciiiiffffiiiicccc ffffuuuunnnnccccttttiiiioooonnnn iiiinnnn aaaa DDDDSSSSOOOO
                ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee        -------- ffffuuuunnnnccccttttiiiioooonnnn____nnnnaaaammmmeeee iiiinnnn mmmmaaaaiiiinnnn pppprrrrooooggggrrrraaaammmm aaaannnndddd ddddssssoooo''''ssss
                <<<< ooooppppttttiiiioooonnnn nnnnooootttt uuuusssseeeedddd >>>>  -------- aaaallllllll ffffuuuunnnnccccttttiiiioooonnnnssss aaaarrrreeee iiiinnnncccclllluuuuddddeeeedddd iiiinnnn qqqquuuueeeerrrryyyy

          +o Sharing of the WorkShop Performance Analyzer
            performance experiment data is supported in _c_v_c_o_v but
            not in _c_v_x_c_o_v of this release.

          +o Output of query results to a printer is not supported
            in this release.  As a workaround, the user can save
            query results to a file, and then send that file to a
            printer.

          +o Experiment data for test sets/test groups cannot be
            moved/copied (mv, cp) without invalidating the data.
            Leaf tests can be moved/copied.

          +o Both the _l_s_t_r_a_c_e feature (argument tracing) and the
            _l_s_s_o_u_r_c_e feature (mapping block counts to actual
            source) require the code to be compiled with -_g.  A
            notable exception to this is return value tracing which
            can trace the return value on functions that are not
            compiled with -_g (e.g., _l_i_b_c functions).











                                  - 41 -



          +o _c_v_c_o_v requires that all instrumentation be performed
            before the experiment is run. This includes
            instrumentation for programs that are forked/exec'ed or
            sproc'ed.  _c_v_m_o_n is the program used by _c_v_c_o_v to
            monitor the experiment.  If _c_v_m_o_n encounters child
            processes, and the coverage experiment includes any
            executables other than the main program, then _c_v_m_o_n
            will instrument the executables for the child processes
            "on the fly".  _c_v_c_o_v will not process coverage for
            these "on the fly" instrumented executables, because
            _c_v_m_o_n has not used the correct coverage instrumentation
            criteria.  This can cause performance and space
            overhead.

          +o IRIX 5.1 and later binaries are supported (no support
            for IRIX 4.0.X binaries) including shared and
            nonshared.

          +o Instrumentation criteria ccccoooouuuunnnnttttssss must at least include
            ----bbbbbbbbccccoooouuuunnnntttt.  For example, if user want to test function
            pointers the instrumentation file must contain the
            following line,

                CCCCOOOOUUUUNNNNTTTTSSSS ----bbbbbbbbccccoooouuuunnnnttttssss ----ffffppppccccoooouuuunnnnttttssss

          +o The current model for running instrumented programs
            requires that a separate process (_c_v_m_o_n) monitor the
            programs that are undergoing coverage analysis.  This
            requires existing test scripts to be modified in the
            following manner:

                oooolllldddd ssssccccrrrriiiipppptttt::::
                   #### pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222
                nnnneeeewwww ssssccccrrrriiiipppptttt::::
                   #### ccccvvvvccccoooovvvv mmmmkkkktttteeeesssstttt ----ccccmmmmdddd """"pppprrrrooooggggrrrraaaammmm aaaarrrrgggg1111 aaaarrrrgggg2222"""" ----tttteeeessssttttnnnnaaaammmmeeee tttteeeesssstttt
                   #### ccccvvvvccccoooovvvv rrrruuuunnnntttteeeesssstttt tttteeeesssstttt

          +o There is potentially a large amount of data that can be
            captured when running multiple tests for large
            programs.  There are several options to the _r_u_n_t_e_s_t
            command that help manage this data.

            The -_n_o_a_r_c option is used to eliminate the capture of
            arc data in the experiment result (e.g., arc AB is
            equivalent to function A calls function B from line X).
            This significantly reduces the amount of overall count
            information for the test coverage result.

            The -_r_m_s_u_b option is used to retain the overall results
            for the top level test set or test group, not for the
            individual subtests.  There are several interactions of











                                  - 42 -



            the -_r_m_s_u_b and -_s_u_m options worth noting.  If the
            -_r_m_s_u_b option is used, a subsequent "runtest" using the
            -_s_u_m option will not accumulate the counts data for
            these two runs.  In this case only the second run will
            be in the top level test set/test group.  The -_s_u_m
            option will sum up data only according to the count
            data that is in all the subtests currently and does not
            use the information in the top level test set or test
            group.  When using the -_s_u_m and -_r_m_s_u_b options
            together, the count data will be accumulated and the
            subtest data will be deleted.

            The -_c_o_m_p_r_e_s_s option is used to compress experiment
            database using standard utility _c_o_m_p_r_e_s_s.

            The -_b_i_t_c_o_u_n_t option is used to convert experiment
            database to 1-bit-per-count format in recording
            experiment so that it will save disk space up to 32
            times. However, count number for basic blocks and
            branch coverage information will be lost.

          +o Source highlighting for statement that cover multiple
            lines only highlights the last line. This is due to a
            limitation in symbol table data generated by the
            compiler.  For example, in the following source
            statement only the second line will be highlighted:

                    pppprrrriiiinnnnttttffff((((""""TTTThhhhiiiissss iiiissss aaaa tttteeeesssstttt ffffoooorrrr %%%%ssss aaaatttt %%%%dddd"""",,,,
            0000            tttteeeessssttttnnnnaaaammmmeeee,,,,wwwwhhhhiiiicccchhhhDDDDrrrriiiivvvveeee))));;;;

          +o If the DSO cache directory has been removed, all the
            existing experiments may be invalid and _T_e_s_t_e_r may not
            work.

       5.8.2  _W_o_r_k_S_h_o_p__T_e_s_t_e_r__B_u_g_s

          +o Programs that use _a_r_g_v[_0] to build hardcoded filenames
            get confused by the renamed instrumented program (e.g.,
            <program> becomes <program_Instr>).


       5.9  _W_o_r_k_S_h_o_p__E_n_v_i_r_o_n_m_e_n_t

          +o If the colors of your WorkShop windows look too dark to
            read or conversely if they look completely washed out,
            there may be a discrepancy between the gamma value you
            are using and the value your X server is using.  The
            default value of gamma on installation is 1.7 but users
            running X programs may prefer a value of 1.0.













                                  - 43 -



            Workaround: If you change your gamma value, by running
            the _g_a_m_m_a program (installed with _e_o_e_2._s_w._g_l_t_o_o_l_s),
            restart your X server.

          +o When starting up WorkShop, if you see the messages

            ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
            ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
            WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
            ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
            ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt ttttyyyyppppeeee ddddaaaattttaaaabbbbaaaasssseeee....
            ttttttttsssseeeessssssssiiiioooonnnn:::: eeeexxxxiiiittttiiiinnnngggg
            WWWWaaaarrrrnnnniiiinnnngggg:::: ttttttttsssseeeessssssssiiiioooonnnn:::: ssssiiiigggg____hhhhaaaannnnddddlllleeeerrrr:::: NNNNoooo cccchhhhiiiilllldddd pppprrrroooocccceeeesssssssseeeessss
            ttttttttsssseeeessssssssiiiioooonnnn:::: CCCCaaaannnn''''tttt iiiinnnniiiitttt sssseeeerrrrvvvveeeerrrr....
            TTTTttttuuuuttttiiiillll:::: CCCCaaaannnnnnnnooootttt ooooppppeeeennnn oooouuuurrrr TTTToooooooollllTTTTaaaallllkkkk pppprrrroooocccceeeessssssss iiiidddd
            ttttttttuuuuttttiiiillll:::: CCCCoooouuuullllddddnnnn''''tttt ccccoooonnnnnnnneeeecccctttt ttttoooo ttttttttsssseeeessssssssiiiioooonnnn sssseeeerrrrvvvviiiicccceeee((((ssss))))....

            check if you have the _C_E_P_A_T_H environment variable set.
            ToolTalk will use the _C_E_P_A_T_H variable for its
            definition of where the types database are located.
            WorkShop expects to find them in the default system
            database, /_e_t_c/_t_t/_t_y_p_e_s._x_d_r. Unsetting this environment
            variable will fix the startup problem.

          +o When starting up WorkShop, you may occassionally see
            the message

            ////uuuussssrrrr////ssssbbbbiiiinnnn////ttttttttsssseeeessssssssiiiioooonnnn:::: WWWWaaaarrrrnnnniiiinnnngggg:::: ccccoooouuuullllddddnnnn''''tttt aaaaccccqqqquuuuiiiirrrreeee XXXX sssseeeelllleeeeccccttttiiiioooonnnn

            ToolTalk displays this message when its internal state
            notes that someone else (i.e. another _t_t_s_e_s_s_i_o_n) has
            already owned the X selection that it is trying to
            aquire.  This message is harmless and can be ignored.

          +o The network license mechanism used by WorkShop performs
            periodic checks to ensure that a license is available.
            Once obtained, a license is valid for 20 minutes. The
            license is validated every 10 minutes, and renewed for
            an additional 20 minutes if all is well. This process
            requires that WorkShop be actively running to be able
            to perform these checks. If the tool is unable to check
            the license server for 20 minutes, the license is lost,
            and the tool must be restarted to get a new license.
            Therefore, suspending a WorkShop process (using <Ctrl-
            Z>, for example) for more than a few minutes loses the
            tool's license.

          +o The WorkShop environment works with one configuration
            management system at a time. This affects all users
            running WorkShop on that machine.












                                  - 44 -



          +o The default for string data is to display it as a hex
            address.  If you prefer the behavior of showing a
            string for _c_h_a_r *, you can set ****aaaauuuuttttooooSSSSttttrrrriiiinnnnggggFFFFoooorrrrmmmmaaaatttt to
            TTTTrrrruuuueeee in your ._X_d_e_f_a_u_l_t_s.  This will automatically
            change the result format from the default to string for
            _c_h_a_r * and _c_h_a_r <_a_r_r_a_y> expressions in the
            ExpressionView, VarBrowser, and DataBrowser.

          +o Customers displaying to non-SGI X displays and having
            difficulties with ExecutionView startup (a busy cursor
            that never goes away) should try switching
            ****eeeexxxxeeeeccccuuuuttttiiiioooonnnnVVVViiiieeeewwww****TTTTeeeerrrrmmmmiiiinnnnaaaallllCCCCoooommmmmmmmaaaannnndddd in
            /_u_s_r/_W_o_r_k_S_h_o_p/_u_s_r/_l_i_b/_X_1_1/_a_p_p-_d_e_f_a_u_l_t_s/_C_v_m_a_i_n from the
            _x_w_s_h version to the commented out _x_t_e_r_m version.